Inside Macintosh: QuickTime
This section describes the functions and structure associated with the text media handler, which allows you to display text in movies. You can use text media handlers to
A particular text sample has a default font, size, typeface, and color as well as a location (text box) within the track bounds to be drawn. The data format allows you to include style run information for the text. You can set flags to clip the display to the text box, inhibit automatic scaling of text as the track bounds are scaled, scroll the text, and specify if text is to be displayed at all.
The Movie Toolbox provides functions to help you add text samples to a track. You can use the TextMediaAddTextSample function to add text to a media. The TextMediaAddTESample function allows you to specify a TextEdit handle (which may have multiple style runs) to be added to a media. The TextMediaAddHiliteSample function allows you to indicate highlighting for text that has just been added with the TextMediaAddTextSample or TextMediaAddTESample function. For more information on styled text, style runs, and TextEdit, see Inside Macintosh: Text.
The format of the text data that is added to the media is a 16-bit length word followed by the text. The length word specifies the number of bytes in the text. Optionally, one or more atoms of additional data may follow. An atom is structured as a 32-bit length word followed by a 32-bit type followed by some data. The length word includes the size of the data as well as the length and type fields (in other words, the size of the data plus 8).
Text atom types include the style atom ( 'styl' ), the shrunken text box atom ( 'tbox' ), the highlighting atom ( 'hlit' ), the scroll delay atom ( 'dlay' ), and the highlight color atom ( 'hclr' ).
The format of the style atom is the same as TextEdit's StScrpRec data type. A StScrpRec data type is a short integer specifying the number of style runs followed by that number of ScrpSTElement data types, each specifying a different style run.
The shrunken text box atom is added when you set the dfShrinkTextBoxToFit display flag (in the TextMediaAddTextSample or TextMediaAddTESample function). Its format is simply the rectangle of the shrunken box (16 bytes total, including length and type).
The highlighting atom is added if the hiliteStart and hiliteEnd parameters are set appropriately in the TextMediaAddTextSample or TextMediaAddTESample function. When TextMediaAddHiliteSample is called, an empty text sample (the first 2 bytes are 0) with a highlighting atom is added to the media. The format is two long integers indicating the start and end of the highlighting (16 bytes total).
The scroll delay atom specifies the scroll delay for a sample. It is a long value that specifies the delay time. It consists of 12 bytes, including the length and type fields.
The highlight color atom specifies the highlight color for a sample. Its format is an RGBColor data type (that is, 2 bytes red, 2 bytes green, and 2 bytes blue). It consists of 14 bytes, including the length and type fields.
The text description structure is defined as follows:
typedef struct TextDescription {
long size; /* total size of this text
description structure */
long type; /* type of data in this
structure such as
'text' */
long resvd1; /* reserved for use by
Apple--set to 0 */
long resvd2; /* reserved for use by
Apple--set to 0 */
short dataRefIndex; /* index to data references */
long displayFlags; /* display flags for text */
long textJustification;
/* text justification flags */
RGBColor gColor; /* background color */
Rect defaultTextBox; /* location of the text within
track bounds */
ScrpSTElement defaultStyle;
/* default style--
TextEdit structure */
} TextDescription, *TextDescriptionPtr, **TextDescriptionHandle;
The TextMediaAddTextSample , TextMediaAddTESample , and TextMediaAddHiliteSample functions described in the sections that follow convert text into the text media format and add it to the media. To use these functions, you need to
The movie import and export components help to get common data types (such as 'PICT' or 'snd ' ) into and out of movies easily. The text import component allows you to get text into a movie using the following principles:
If you want more control over how the text is added (for example, if you want to set some display flags or a new track position), your application must
For details on the movie import and export components, see Inside Macintosh: QuickTime Components.
The Movie Toolbox provides functions that allow you to search for and highlight text. You can use the TextMediaFindNextText function to search for text in a text track, and the TextMediaHiliteTextSample function to highlight specified text in a text track.
You can use the TextMediaSetTextProc function (also described in this section) to specify a customized function whenever a new text sample is added to a movie. The application-defined text function MyTextProc is described in "Text Functions" .
The TextMediaAddTextSample function adds a single block of styled text to an existing media.
pascal ComponentResult TextMediaAddTextSample
(MediaHandler mh, Ptr text,
unsigned long size,
short fontNumber,
short fontSize,
Style textFace,
RGBColor *textColor,
RGBColor *backColor,
short textJustification,
Rect *textBox,
long displayFlags,
TimeValue scrollDelay,
short hiliteStart,
short hiliteEnd,
RGBColor *rgbHiliteColor,
TimeValue duration,
TimeValue *sampleTime);
The TextMediaAddTESample function allows you to specify a TextEdit handle (which may contain multiple style runs) to be added to the specified media.
pascal ComponentResult TextMediaAddTESample
(MediaHandler mh, TEHandle hTE,
RGBColor *backColor,
short textJustification,
Rect *textBox,
long displayFlags,
TimeValue scrollDelay,
short hiliteStart,
short hiliteEnd,
RGBColor *rgbHiliteColor,
TimeValue duration,
TimeValue *sampleTime);
The TextMediaAddHiliteSample function provides dynamic highlighting of text.
pascal ComponentResult TextMediaAddHiliteSample
(MediaHandler mh,
short hiliteStart,
short hiliteEnd,
RGBColor *rgbHiliteColor,
TimeValue duration,
TimeValue *sampleTime)
The TextMediaAddHiliteSample function essentially extends the duration of the text that has just been added, using the highlighting indicated by the hiliteStart and hiliteEnd parameters. You must call the TextMediaAddHiliteSample function after calling TextMediaAddTextSample or TextMediaAddTESample . Since TextMediaAddHiliteSample uses the concept of difference frames, the highlighted samples must immediately follow their associated text samples.
The TextMediaFindNextText function searches for text with a specified media handler starting at a given time.
pascal ComponentResult TextMediaFindNextText
(MediaHandler mh,
Ptr text, long size,
short findFlags,
TimeValue startTime,
TimeValue *foundTime,
TimeValue *foundDuration,
long *offset);
When you call the TextMediaHiliteTextSample function with a given text media handler, your application can specify selected text to be highlighted.
pascal ComponentResult TextMediaHiliteTextSample
(MediaHandler mh,
TimeValue sampleTime,
short hiliteStart,
short hiliteEnd
RGBColor *rgbHiliteColor);
Your application can use the TextMediaSetTextProc function to specify a customized function that is to be called whenever a text sample is displayed in a movie.
pascal ComponentResult TextMediaSetTextProc
(MediaHandler mh,
TextMediaProcPtr TextProc,
long refcon);
pascal OSErr MyTextProc (Handle theText,
Movie theMovie,
short *displayFlag,
long refcon);